home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / files / functions.doc < prev    next >
Text File  |  1996-10-10  |  21KB  |  597 lines
  1. 2    FILES - FUNCTIONS
  2.  
  3. 2.1  QUICK REFERENCE
  4.  
  5. Here is a complete list of all file functions described in this
  6. chapter:
  7.  
  8.   Function        Description                                   
  9.   -------------------------------------------------------------
  10.   Close()         Closes a previously opened file.
  11.   Lock()          Puts a shared or excusive lock on an object.
  12.   Open()          Opens a new or old file for IO.
  13.   OpenFromLock()  Opens an already locked file.
  14.   Read()          Reads a specified number of bytes in a file.
  15.   Seek()          Moves the file cursor inside a file.
  16.   UnLock()        Unlocks a previously locked object.
  17.   Write()         Writes a specified number of bytes to a file.
  18.   -------------------------------------------------------------
  19.  
  20.  
  21.  
  22. ---------------------------------------------------------------
  23.  
  24. Close()
  25.  
  26. ROM library: "dos.library/Close", (All Versions)
  27. #include <clib/dos_protos.h>
  28.  
  29. Closes a previously opened file.
  30.  
  31. Synopsis: ok = Close( file );
  32.  
  33.   ok:     (LONG) If the file could successfully be saved TRUE
  34.           is returned. On the other hand, if there was some
  35.           sort of problem FALSE is returned.
  36.           
  37.           Even if the file could not be closed successfully
  38.           will the file cursor and all memory which have
  39.           previously been allocated internally now been
  40.           removed and deallocated. So even if you could not
  41.           close the file successfully you should NOT try to
  42.           close it again (that would crash the system)!
  43.           
  44.           If the file could not be closed there is actually
  45.           very little we can do about it. We might want to
  46.           resave some data (in another file) if we are afraid
  47.           the data otherwise might be lost, but we can not
  48.           do anything about the actual error. Just remember
  49.           that you must not try to close the file again, nor
  50.           to use it any more!
  51.  
  52.           On the old systems prior to Release 2 (older than
  53.           V36) the Close() do not return anything.
  54.  
  55.   file:   (BPTR) A BCPL pointer to an already open file which
  56.           should now be cosed.
  57.  
  58. Remember to close ALL files you have opened!
  59.  
  60. Here is a simple example on how to use the Close() function:
  61.  
  62.   - - -
  63.  
  64.   /* Close the file: */
  65.   if( Close( my_file ) )
  66.     printf( "File closed!\n" );
  67.   else
  68.     printf( "Error! File could not be closed!\n" );
  69.  
  70.   /* Remember that even if the file could not be */
  71.   /* closed we must NOT try to close it again!   */
  72.  
  73.  
  74. See also: IoErr(), Lock(), Open(), OpenFromLock(), Read(),
  75.           Seek(), UnLock(), Write()
  76.  
  77. ---------------------------------------------------------------
  78.  
  79. Lock()
  80.  
  81. ROM library: "dos.library/Lock", (All Versions)
  82. #include <clib/dos_protos.h>
  83.  
  84. Puts a shared or excusive lock on an object (e.g. file).
  85.  
  86. Synopsis:    lock = Lock( file_name, mode );
  87.  
  88.   lock:      (BPTR) If the file could be locked a BPTR (BPCL
  89.              pointer) is returned. If the file on the other
  90.              hand could not be locked NULL is returned.
  91.              Possible reasons why the lock failed:
  92.              
  93.                1. The file simply does not exist.
  94.  
  95.                2. Some other program has an exclusive lock on
  96.                   the file, and consequntly no others may lock
  97.                   it (both shared and exclusive lock requests
  98.                   will fail).
  99.  
  100.                3. Som other program has a shared lock on the
  101.                   file but you wanted an exclusive lock. (If
  102.                   the file has a shared lock on it, and you
  103.                   tries to add another shared lock on it there
  104.                   will not be any problems.)
  105.  
  106.   file_name: (STRPTR) Pointer to a text string which contains
  107.              the name of the file you want to lock. If the file
  108.              is not located in the current directory you have
  109.              to include the necessary path.
  110.  
  111.   mode:      (LONG) On the Amiga there exist two types of
  112.              locks: (The flags are defined in header file
  113.              "dos/dos.h")
  114.  
  115.                SHARED_LOCK:     Other programs may read data in
  116.                                 the file, but no one else may
  117.                                 alter the file. (You can also
  118.                                 use the flag "ACCESS_READ"
  119.                                 which does the same thing.)
  120.              
  121.                EXCLUSIVE_LOCK:  No other programs may use this
  122.                                 file. (You can also use the
  123.                                 flag "ACCESS_WRITE" which does
  124.                                 the same thing.)
  125.  
  126.  
  127. Here is a simple example on how to use the Lock() function:
  128.  
  129.   /* A "BCPL" pointer to our lock: */
  130.   BPTR my_lock;
  131.  
  132.   - - -
  133.  
  134.   /* Try to lock the file with an exclusive lock: */
  135.   my_lock = Lock( "Highscore.dat", EXCLUSIVE_LOCK );
  136.  
  137.   /* Check if we have successfully locked the file or not: */
  138.   if( my_lock == NULL )
  139.     printf( "Could not lock the file!\n" );
  140.  
  141.  
  142. See also: Close(), IoErr(), Open(), OpenFromLock(), Read(),
  143.           Seek(), UnLock(), Write()
  144.  
  145. ---------------------------------------------------------------
  146.  
  147. Open()
  148.  
  149. ROM library: "dos.library/Open", (All Versions)
  150. #include <clib/dos_protos.h>
  151.  
  152. Opens a new or old file for input and/or output, and puts a
  153. read" or "write" lock on the file.
  154.  
  155. Synopsis:    my_file = Open( file_name, mode );
  156.  
  157.   my_file:   (BPTR) If the file could be opened a BPTR (BPCL
  158.              pointer) is returned. If the file on the other
  159.              hand could not be opened NULL is returned.
  160.  
  161.   file_name: (STRPTR) Pointer to a text string which contains
  162.              the name of the file you want to open. If the file
  163.              is not located in the current directory you have
  164.              to include any necessary device/directory names.
  165.              (The device/directory part is usually reffered as
  166.              the "path", and tells AmigaDOS where the file can
  167.              be found.)
  168.  
  169.   mode:      (LONG) When you want to open a file you must tell
  170.              AmigaDOS how you want to open the file. For the
  171.              mement there exist three modes: (The flags are
  172.              defined in header file "dos/dos.h")
  173.  
  174.              MODE_OLDFILE:   Opens an existing file for reading
  175.                              and writing. The file will be
  176.                              "locked" so other programs can read
  177.                              it but not modify it before you
  178.                              have "un-locked" the file. This is
  179.                              usually called a "write lock"
  180.                              ("shared lock"). 
  181.  
  182.                              If the file does not exist or it
  183.                              is used by some other program
  184.                              ("read or write locked") Open()
  185.                              will fail and NULL is returned.
  186.  
  187.              MODE_NEWFILE:   Opens a new file for writing. If
  188.                              the file already exist it will be
  189.                              deleted so a new file with the
  190.                              same name can be created.
  191.                              
  192.                              Note that the data in an existing
  193.                              file will be deleted if you use
  194.                              this flag on an already existing
  195.                              file! Be careful so you do not
  196.                              destroy important data!
  197.  
  198.                              The file will be "locked" so no
  199.                              other programs can read nor write
  200.                              to it. This is usually called a
  201.                              "read/write lock" ("exclusive
  202.                              lock")
  203.                              
  204.                              If the file already exist and is
  205.                              used by some other program ("read
  206.                              or write locked") Open() will fail
  207.                              and NULL is returned.
  208.                              
  209.              MODE_READWRITE: Opens an old file as described
  210.                              with the "MODE_OLDFILE" flag.
  211.                              However, if the file does not
  212.                              exist it will be created.
  213.                              
  214.                              If the file is used by some other
  215.                              program ("read or write locked")
  216.                              Open() will fail and NULL is
  217.                              returned.
  218.                           
  219.              Regardless of what mode you chose the file cursor
  220.              will always be positioned in the beginning of the
  221.              file if it could be opened. (The file cursor will
  222.              point to the first byte/character in the file).
  223.  
  224. You may of course have as many files open at the same time as
  225. you want. Note that each file you have opened has its own file
  226. cursor. When you work with one file you do not have to bother
  227. about the other ones. If you move around inside one file the
  228. others files' file cursors will remain unmodified. Of course 
  229. you need a BPTR for each file, and you have to open each file
  230. separately.
  231.  
  232. Here is a simple example on how to use the Open() function:
  233.  
  234.   /* A "BCPL" pointer to our file: */
  235.   BPTR my_file;
  236.  
  237.   - - -
  238.  
  239.   /* Try to open a file as "new": */
  240.   my_file = Open( "Highscore.dat", MODE_NEWFILE );
  241.  
  242.   /* Check if we have successfully opened the file or not: */
  243.   if( my_file == NULL )
  244.     printf( "Could not open the file!\n" );
  245.  
  246.  
  247. See also: Close(), IoErr(), Lock(), OpenFromLock(), Read(),
  248.           Seek(), UnLock(), Write()
  249.  
  250. ---------------------------------------------------------------
  251.  
  252. OpenFromLock()
  253.  
  254. ROM library: "dos.library/OpenFromLock", (V36+)
  255. #include <clib/dos_protos.h>
  256.  
  257. Opens an already locked file.
  258.  
  259. Synopsis:  my_file = OpenFromLock( lock );
  260.  
  261.   my_file: (BPTR) If the file could be opened a BPTR (BPCL
  262.            pointer) is returned. If the file on the other hand
  263.            could not be opened NULL is returned.
  264.  
  265.   lock:    (BPTR) A BPCL pointer to a lock which file should be
  266.            opened. You must of course have locked the file
  267.            successfully before you may open the file with it!
  268.  
  269. Here is a simple example on how to use the OpenFromLock()
  270. function:
  271.  
  272.   /* A "BCPL" pointer to our lock: */
  273.   BPTR my_lock;
  274.  
  275.   /* A "BCPL" pointer to our file: */
  276.   BPTR my_file;
  277.  
  278.   - - -
  279.  
  280.   /* Put an exclusive lock on an existing file: */
  281.   my_lock = Lock( "RAM:HighScore.dat", EXCLUSIVE_LOCK );
  282.  
  283.   /* Could we lock the file successfully? */
  284.   if( !my_lock )
  285.   {
  286.     /* Problems! Inform the user: */
  287.     printf( "Could not put an exclusive lock on the file!\n" );
  288.  
  289.     /* Exit with an error code: */
  290.     exit( 20 );
  291.   }
  292.  
  293.  
  294.   /* We will now try to open the file with help */
  295.   /* of the lock we already have:               */
  296.   my_file = OpenFromLock( my_lock );
  297.   
  298.   /* Have we opened the file successfully? */
  299.   if( !my_file )
  300.   {
  301.     /* Problems! Inform the user: */
  302.     printf( "Error! Could not open the file!\n" );
  303.  
  304.     /* Unlock the file: */
  305.     UnLock( my_lock );
  306.  
  307.     /* Exit with an error code: */
  308.     exit( 21 );
  309.   }
  310.  
  311.   - - -
  312.  
  313.   /* Close the file: */
  314.   Close( my_file );
  315.  
  316.   /* Unlock the file: */
  317.   UnLock( my_lock );
  318.  
  319.  
  320. See also: Close(), IoErr(), Lock(), Open(), Read(), Seek(),
  321.           UnLock(), Write()
  322.  
  323. ---------------------------------------------------------------
  324.  
  325. Read()
  326.  
  327. ROM library: "dos.library/Read", (All Versions)
  328. #include <clib/dos_protos.h>
  329.  
  330. Reads a specified number of bytes in a file.
  331.  
  332. Synopsis: count = Read( file, buffer, size );
  333.  
  334.   count:  (LONG) The function returns the number of bytes
  335.           actually read. When you tell AmigaDOS that you want
  336.           to read X number of bytes it is not certain that you
  337.           actually can do it. The file might be shorter than
  338.           you expected or the file might be corrupted, etc...
  339.  
  340.           The returned value can be:
  341.              
  342.              1. equal to the number of bytes requested. In this
  343.              case everything went as expected. The requested
  344.              number of bytes were read, and there were no
  345.              errors.
  346.              
  347.              2. equal to -1. In this case there was an error
  348.              while the function tried to read the data. How
  349.              much, if any, data were actually read before the
  350.              error occured is imposible to say, and you should
  351.              not use the values in the buffer. If you receive
  352.              this value you may call IoErr() to get more
  353.              information about the error.
  354.  
  355.              3. less than the number of bytes requested, but
  356.              not equal to -1. In this case we have simply
  357.              reached the end of the file, and there was no
  358.              error. 
  359.              
  360.              Please note that reaching the end of the file
  361.              before expected can sometimes indicate that there
  362.              was some sort of error. If you have saved for
  363.              example 10 structures of a certain size, and when
  364.              you later tries to read the file and only get four
  365.              structures there is obviously something wrong. It
  366.              is, however, not a dos error and the file itself
  367.              is ok. It is the data in the file which is
  368.              incorrect, but that is not AmigaDOS's fault.
  369.              
  370.   file:   (BPTR) A BCPL pointer to an already open file.
  371.  
  372.   buffer: (APTR) Pointer to some memory where the collected
  373.           data can be stored.
  374.  
  375.   size:   (LONG) Number of bytes you want to read.
  376.  
  377.  
  378. Note! The function does not check that the buffer you give it
  379. is big enough to store all values you requested! You may never
  380. try to read more bytes than can fit in your buffer!
  381.  
  382. Here is a simple example on how to use the Read() function:
  383.  
  384.   /* Some memory where we will store the collected data: */
  385.   int my_highscore[ 10 ];
  386.  
  387.   /* The number of bytes actually collected: */
  388.   long bytes_read;
  389.  
  390.   - - -
  391.  
  392.   /* Read some data from an already open file: */
  393.   bytes_read = Read( my_file, my_highscore, sizeof( my_highscore ) );
  394.  
  395.   /* Did we get all data? */ 
  396.   if( bytes_read != sizeof( my_highscore ) )
  397.   {
  398.     /* No! We could not read all values! */
  399.     printf( "Error! Could read all values!\n" );
  400.   }
  401.   else
  402.   {
  403.     /* Yes! All recuested data were successfully collected! */
  404.     printf( "Data collected!\n" );
  405.   }
  406.  
  407.  
  408. See also: Close(), IoErr(), Lock(), Open(), OpenFromLock(),
  409.           Seek(), UnLock(), Write()
  410.  
  411. ---------------------------------------------------------------
  412.  
  413. Seek()
  414.  
  415. ROM library: "dos.library/Seek", (All Versions)
  416. #include <clib/dos_protos.h>
  417.  
  418. Moves the file cursor to a specified position in a file.
  419.  
  420. Synopsis:   old_pos = Seek( file, position, offset );
  421.  
  422.   old_pos:  (LONG) The function returns the previous position
  423.             in the file, or -1 if there was an error and the
  424.             file cursor could not be moved. If there was an
  425.             error you should of course not try to read or
  426.             write any data until the problem has been solved
  427.             and you have successfully positioned the file
  428.             cursor.
  429.             
  430.             If there is an error you should call IoErr() to
  431.             get more information about the error.
  432.  
  433.   file:     (BPTR) A BCPL pointer to an already open file.
  434.  
  435.   position: (LONG) The position you want to move the file
  436.             cursor to. Note that this value is an relative
  437.             to the specified "offset position".
  438.  
  439.   offest:   (LONG) The specified position is relative to one
  440.             one of these "offset positions": (The flags are
  441.             defined in header file "dos/dos.h")
  442.  
  443.                OFFSET_BEGINNING: Beginning of the file.
  444.  
  445.                OFFSET_CURRENT:   Current position.
  446.  
  447.                OFFSET_END:       The end of the file.
  448.  
  449.  
  450. If you want to move the file cursor to the beginning of the
  451. file (pointing to the first byte) you set the offset position
  452. to "OFFSET_BEGINNING" and the position value to 0.
  453.  
  454. If you on the other hand want to move the file cursor to the
  455. end of the file you set the offset position to "OFFSET_END" and
  456. the position value to 0.
  457.  
  458. To move 10 bytes forward from the current position you set the
  459. offset position to "OFFSET_CURRENT" and the position value to
  460. 10. To move 10 bytes backwards you set the position value to
  461. -10.
  462.  
  463. Here are some simple examples on how to use the Seek() function:
  464.  
  465.   /* Move the file cursor to the end of the file:  */
  466.   Seek( my_file, 0, OFFSET_END );
  467.  
  468.   /* Move the file cursor to the beginning of the file:  */
  469.   Seek( my_file, 0, OFFSET_BEGINNING );
  470.  
  471.   /* Move the file cursor 10 bytes forward */
  472.   /* from the current position:            */
  473.   Seek( my_file, 10, OFFSET_CURRENT );
  474.  
  475.   /* Move the file cursor 10 bytes backwards */
  476.   /* from the current position:              */
  477.   Seek( my_file, -10, OFFSET_CURRENT );
  478.  
  479.  
  480. See also: Close(), IoErr(), Lock(), Open(), OpenFromLock(),
  481.           Read(), UnLock(), Write()
  482.  
  483. ---------------------------------------------------------------
  484.  
  485. UnLock()
  486.  
  487. ROM library: "dos.library/UnLock", (All Versions)
  488. #include <clib/dos_protos.h>
  489.  
  490. Unlocks a previously locked object (e.g. file).
  491.  
  492. Synopsis: UnLock( lock );
  493.  
  494.   lock:   (BPTR) A BPCL pointer to a lock that should be
  495.           unlocked. Remember that every file that you have
  496.           locked must be unlocked when you do not need the
  497.           look any more!
  498.  
  499. Here is a simple example on how to use the UnLock() function:
  500.  
  501.   - - -
  502.  
  503.   /* Unlock the file: */
  504.   UnLock( my_lock );
  505.  
  506.  
  507. See also: Close(), IoErr(), Lock(), Open(), OpenFromLock(),
  508.           Read(), Seek(), Write()
  509.  
  510. ---------------------------------------------------------------
  511.  
  512. Write()
  513.  
  514. ROM library: "dos.library/Write", (All Versions)
  515. #include <clib/dos_protos.h>
  516.  
  517. Writes a specified number of bytes to a file.
  518.  
  519. Synopsis: count = Write( file, buffer, size );
  520.  
  521.   count:  (LONG) The function returns the number of bytes
  522.           actually written. When you tell AmigaDOS that you want
  523.           to write X number of bytes it is not certain that you
  524.           actually can do it. The file is maybe write protected,
  525.           or the disk is full etc...
  526.  
  527.           The returned value can be:
  528.              
  529.              1. equal to the number of bytes requested. In this
  530.              case everything went as expected. The requested
  531.              number of bytes were written, and there were no
  532.              errors.
  533.              
  534.              2. equal to -1. In this case there was an error
  535.              while the function tried to write the data. No
  536.              data will have been saved. If you receive this
  537.              value you may call IoErr() to get more information
  538.              about the error.
  539.  
  540.              3. less than the number of bytes requested, but
  541.              not equal to -1. In this case the operation was
  542.              aborted because of some external event (disk full
  543.              etc...), and the value returned tells us how many
  544.              bytes that have been saved.
  545.              
  546.              If you could not save all the data you should
  547.              in most situations remove the half filled file
  548.              (it is probably useless if not all data could
  549.              be saved) and ask the user to for example insert
  550.              a new disk etc... depending on what have happened.
  551.              
  552.              Do NOT just tell the user that there was a problem
  553.              and then quit! (In small examples and if the data
  554.              is unimportant this is of course OK, but bigger
  555.              applications should try to solve the problem.)
  556.              
  557.   file:   (BPTR) A BCPL pointer to an already open file.
  558.  
  559.   buffer: (APTR) Pointer to some memory where the data that
  560.           should be written (saved) are stored.
  561.  
  562.   size:   (LONG) Number of bytes you want to write.
  563.  
  564.  
  565. Here is a simple example on how to use the Write() function:
  566.  
  567.   /* Some data we want to save: */
  568.   int my_highscore[ 10 ] =
  569.     { 34, 76, 328, 723, 1027, 1201, 1416, 2645, 3050, 3876 };
  570.  
  571.   /* The number of bytes actually written: */
  572.   long bytes_written;
  573.  
  574.   - - -
  575.  
  576.   /* Write some data to a file: */
  577.   bytes_written = Write( my_file, my_highscore, sizeof( my_highscore ) );
  578.  
  579.   /* Did we write all data? */ 
  580.   if( bytes_written != sizeof( my_highscore ) )
  581.   {
  582.     /* No! We could not write (save) all data! */
  583.     printf( "Error! Could not save all values!\n" );
  584.   }
  585.   else
  586.   {
  587.     /* Yes, all numbers have been written to the file! */
  588.     printf( "All values were saved successfully!\n" );
  589.   }
  590.  
  591.   
  592. See also: Close(), IoErr(), Lock(), Open(), OpenFromLock(),
  593.           Read(), Seek(), UnLock()
  594.  
  595. ---------------------------------------------------------------
  596.  
  597.